Device#

The Device namespace provides access to information about the current device and its environment, including hardware characteristics, system details, screen metrics, battery status, orientation, proximity sensor state, locale and language settings, wake lock control, and network interfaces.

This API is commonly used to adapt UI layouts, behavior, and feature availability based on the device’s runtime context.

#Memory

These read-only properties are available globally through Device without an import. All values are in bytes and are read when accessed.

processMemoryUsage includes the host's allocations and other scripts sharing that process; it does not isolate one script's JavaScript heap. In a widget or another extension, it measures that extension's process, not the main app or the sum of all app processes. Footprint includes compressed memory accounting and differs from resident memory.

availableMemory is advisory and can change immediately, including when the system changes the process memory limit. Read it fresh when needed. A value of 0 can mean that the process has reached/exceeded its limit or that the system cannot supply an app memory budget. It is not a guarantee that an allocation will succeed. Neither available memory nor total physical memory should be used as a target allocation size.

Read memory usage at meaningful checkpoints or at a modest interval; avoid tight polling. Convert bytes to MiB by dividing by 1024 * 1024.

import { Script } from "scripting"

const usage = Device.processMemoryUsage
console.log("Device memory (MiB):", Device.physicalMemory / 1024 / 1024)
console.log("Process footprint (MiB):", usage === null ? "unavailable" : usage / 1024 / 1024)
console.log("Process available memory (MiB):", Device.availableMemory / 1024 / 1024)
Script.exit()

#Orientation

Represents the physical orientation of the device.

type Orientation =
  | "portrait"
  | "portraitUpsideDown"
  | "landscapeLeft"
  | "landscapeRight"
  | "faceUp"
  | "faceDown"
  | "unknown"

#Description

• portrait: Portrait orientation, default upright position
• portraitUpsideDown: Portrait orientation, upside down
• landscapeLeft: Landscape orientation rotated to the left
• landscapeRight: Landscape orientation rotated to the right
• faceUp: Device is lying flat with the screen facing upward
• faceDown: Device is lying flat with the screen facing downward
• unknown: Orientation cannot be determined

#InterfaceOrientation

Represents the supported interface orientations for the app.

type InterfaceOrientation =
  | "portrait"
  | "portraitUpsideDown"
  | "landscape"
  | "landscapeLeft"
  | "landscapeRight"
  | "all"
  | "allButUpsideDown"

#Description

• portrait: Portrait orientation, default upright position
• portraitUpsideDown: Portrait orientation, upside down
• landscape: Landscape orientation, either left or right
• landscapeLeft: Landscape orientation rotated to the left
• landscapeRight: Landscape orientation rotated to the right
• all: All supported orientations
• allButUpsideDown: All supported orientations except upside down

#NetworkInterface

Describes a single network interface address.

type NetworkInterface = {
  address: string
  netmask: string | null
  family: "IPv4" | "IPv6"
  mac: string | null
  isInternal: boolean
  cidr: string | null
}

#Properties

• address: IP address
• netmask: Subnet mask
• family: Address family, either IPv4 or IPv6
• mac: MAC address (may be null depending on system restrictions)
• isInternal: Indicates whether the interface is internal (for example, loopback)
• cidr: CIDR notation, such as 192.168.1.10/24

#BatteryState

Represents the current battery state.

type BatteryState = "full" | "charging" | "unplugged" | "unknown"

#Description

• full: Battery is fully charged
• charging: Device is currently charging
• unplugged: Device is not connected to power
• unknown: Battery state cannot be determined

#Device Information

#model

const model: string

The device model, such as "iPhone" or "iPad".

#localizedModel

const localizedModel: string

The localized name of the device model.

#appVersion / appBuildNumber

Readonly synchronous strings identifying the Scripting App, including when a script runs in an extension. appVersion reads CFBundleShortVersionString; appBuildNumber reads CFBundleVersion. Build numbers stay strings (they can contain dots or leading zeros). If the containing App cannot be read, the running bundle is used; a missing value is an empty string.

Device is an injected global; use it directly without an import:

console.log(`Scripting ${Device.appVersion} (${Device.appBuildNumber})`)
console.log(`OS ${Device.systemVersion}`)

These values identify Scripting, independently of a script's own version and the OS version. They require no permission or network access.

#systemVersion

const systemVersion: string

The current operating system version, for example "18.2".

#systemName

const systemName: string

The name of the operating system, such as "iOS", "iPadOS", or "macOS".

#isiPad / isiPhone

const isiPad: boolean
const isiPhone: boolean

Indicates whether the current device is an iPad or an iPhone.

#screen

const screen: {
  width: number
  height: number
  scale: number
}

Screen metrics:

• width: Screen width in logical pixels
• height: Screen height in logical pixels
• scale: Screen scale factor (for example, 2 or 3)

#Battery and Sensors

#batteryState

const batteryState: BatteryState

The current battery state.

#batteryLevel

const batteryLevel: number

The current battery level, expressed as a value between 0.0 and 1.0.

#proximityState

const proximityState: boolean

The state of the proximity sensor. true indicates that the device is close to the user, such as during a phone call.

#Orientation and Layout

#isLandscape / isPortrait / isFlat

const isLandscape: boolean
const isPortrait: boolean
const isFlat: boolean

• isLandscape: Indicates whether the device is in a landscape orientation
• isPortrait: Indicates whether the device is in a portrait orientation
• isFlat: Indicates whether the device is lying flat (face up or face down)

#orientation

const orientation: Orientation

The current physical orientation of the device.

#supportedInterfaceOrientations

var supportedInterfaceOrientations: InterfaceOrientation[]

The list of supported interface orientations. You can set this property to limit the orientations that your page supports.

#Example

function Page() {
  useEffect(() => {
    Device.supportedInterfaceOrientations = ["all"]
    return () => {
      Device.supportedInterfaceOrientations = Device.userConfiguredInterfaceOrientations
    }
  }, [])
  return <VStack>...</VStack>
}

#userConfiguredInterfaceOrientations

const userConfiguredInterfaceOrientations: InterfaceOrientation[]

The list of interface orientations configured by the user. You can use this value to set supportedInterfaceOrientations to restore the default interface orientations.

#Appearance and Environment

#colorScheme

const colorScheme: ColorScheme

The current system color scheme, such as light or dark mode.

#isiOSAppOnMac

const isiOSAppOnMac: boolean

Indicates whether the current process is an iPhone or iPad app running on macOS.

#Locale and Language

#systemLocale

const systemLocale: string

The current system locale, for example "en_US".

#preferredLanguages

const preferredLanguages: string[]

The user’s preferred languages, for example:

["en-US", "zh-Hans-CN"]

#systemLocales (Deprecated)

const systemLocales: string[]

Deprecated. Use preferredLanguages instead.

#systemLanguageTag

const systemLanguageTag: string

The current language tag, such as "en-US".

#systemLanguageCode

const systemLanguageCode: string

The current language code, such as "en".

#systemCountryCode

const systemCountryCode: string | undefined

The current country code, such as "US".

#systemScriptCode

const systemScriptCode: string | undefined

The script code of the current locale, such as "Hans" for Simplified Chinese.

#Wake Lock

#isWakeLockEnabled

const isWakeLockEnabled: Promise<boolean>

Retrieves whether the wake lock is currently enabled, preventing the device from automatically sleeping.

#setWakeLockEnabled

function setWakeLockEnabled(enabled: boolean): void

Enables or disables the wake lock.

Notes:

• Available only in the Scripting app
• When enabled, the device will remain awake and not auto-lock

#Battery Listeners

#addBatteryStateListener

function addBatteryStateListener(
  callback: (state: BatteryState) => void
): void

Registers a listener for battery state changes.

#removeBatteryStateListener

function removeBatteryStateListener(
  callback?: (state: BatteryState) => void
): void

Removes a battery state listener. If callback is not provided, all battery state listeners are removed.

#addBatteryLevelListener

function addBatteryLevelListener(
  callback: (level: number) => void
): void

Registers a listener for battery level changes.

#removeBatteryLevelListener

function removeBatteryLevelListener(
  callback?: (level: number) => void
): void

Removes a battery level listener. If callback is not provided, all battery level listeners are removed.

#Orientation Listeners

#addOrientationListener

function addOrientationListener(
  callback: (orientation: Orientation) => void
): void

Starts observing device orientation changes.

Notes:

• This method must be called before orientation updates are delivered
• Orientation updates do not work when system orientation lock is enabled

#removeOrientationListener

function removeOrientationListener(
  callback?: (orientation: Orientation) => void
): void

Removes an orientation change listener. If callback is not provided, all orientation listeners are removed and observation is stopped.

#Proximity Listeners

#addProximityStateListener

function addProximityStateListener(
  callback: (state: boolean) => void
): void

Registers a listener for proximity sensor state changes.

#removeProximityStateListener

function removeProximityStateListener(
  callback?: (state: boolean) => void
): void

Removes a proximity state listener. If callback is not provided, all proximity listeners are removed.

#Network

#networkInterfaces

function networkInterfaces(): Record<string, NetworkInterface[]>

Returns the network interfaces available on the device.

Return value:

• Keys are interface names (such as en0, lo0)
• Values are arrays of NetworkInterface objects associated with each interface

This method is useful for network diagnostics, retrieving local IP addresses, and debugging connectivity issues.